API dokumentacijos evoliucija: išsamus OpenAPI specifikacijos vadovas

Šiuolaikiniame itin susietame skaitmeniniame pasaulyje programų sąsajos (API) yra nematomos gijos, jungiančios mūsų programinę įrangą ir paslaugas. Jos yra modernios skaitmeninės ekonomikos variklis, leidžiantis veikti viskam – nuo mobiliosios bankininkystės iki socialinių tinklų naujienų srautų. Tačiau, sparčiai augant API skaičiui, kyla esminis iššūkis: kaip programuotojai, sistemos ir organizacijos gali bendrauti efektyviai ir be dviprasmybių? Kaip užtikrinti, kad viename pasaulio krašte sukurta API galėtų būti sklandžiai naudojama paslaugos kitame?

Atsakymas slypi bendroje kalboje, universaliame kontrakte, kuris aprašo API galimybes taip, kad suprastų tiek žmonės, tiek mašinos. Tai yra OpenAPI specifikacijos (OAS) vaidmuo. Tai daugiau nei tik dokumentacija – OAS yra pagrindinis standartas, skirtas RESTful API projektavimui, kūrimui, dokumentavimui ir naudojimui. Šis vadovas jus išsamiai supažindins su OpenAPI specifikacija, paaiškins, kas tai yra, kodėl tai svarbu ir kaip galite ją panaudoti kurdami geresnius, labiau bendradarbiavimu pagrįstus skaitmeninius produktus.

Kas yra OpenAPI specifikacija? Universali kalba API sąsajoms

Iš esmės OpenAPI specifikacija yra standartizuotas, nuo programavimo kalbos nepriklausomas RESTful API sąsajų aprašas. Ji leidžia apibrėžti visą API struktūrą viename faile, paprastai parašytame YAML arba JSON formatu. Įsivaizduokite tai kaip detalų pastato brėžinį; prieš pradedant bet kokias statybas, brėžinyje nurodomas kiekvienas kambarys, kiekvienos durys ir kiekvienas elektros lizdas. Panašiai OpenAPI dokumentas aprašo:

• Visus galimus galinius taškus arba kelius (pvz., /users, /products/{id}).
• Operacijas (HTTP metodus), galimas kiekviename galiniame taške (pvz., GET, POST, PUT, DELETE).
• Parametrus, antraštes ir užklausų turinius kiekvienai operacijai.
• Atsakymų objektų struktūrą kiekvienai operacijai, įskaitant skirtingus HTTP būsenos kodus.
• Autentifikacijos metodus, kontaktinę informaciją, licencijavimą, naudojimo sąlygas ir kitus svarbius metaduomenis.

Trumpa istorija: nuo „Swagger“ iki „OpenAPI“

Galbūt girdėjote terminą „Swagger“, vartojamą kaip „OpenAPI“ sinonimą. Svarbu suprasti jų ryšį. Specifikacija pradėjo savo kelią kaip „Swagger“ specifikacija 2010 m., sukurta Tony Tam iš „Reverb“. Jai įgavus didžiulį populiarumą, 2015 m. ji buvo perduota „Linux Foundation“ ir pervadinta į OpenAPI specifikaciją, taip įtvirtinant ją kaip tikrą atvirą standartą, kurį globoja „OpenAPI Initiative“ – pramonės lyderių, tokių kaip „Google“, „Microsoft“ ir IBM, konsorciumas.

Šiandien Swagger reiškia galingų atvirojo kodo ir profesionalių įrankių rinkinį, veikiantį su OpenAPI specifikacija, pavyzdžiui, „Swagger UI“ interaktyviai dokumentacijai generuoti ir „Swagger Editor“ pačiai specifikacijai rašyti.

Pagrindiniai OpenAPI dokumento komponentai

OpenAPI dokumentas yra struktūrizuotas naudojant specifinių laukų rinkinį. Nors iš pirmo žvilgsnio tai gali atrodyti bauginančiai, jis yra logiškai sutvarkytas. Panagrinėkime pagrindinius OpenAPI 3.x dokumento elementus, naudodami YAML formatą dėl jo geresnio skaitomumo žmonėms.

1. `openapi` ir `info` objektai: pagrindai

Kiekvienas OpenAPI dokumentas prasideda nuo versijos ir esminių metaduomenų.

• openapi: Eilutė, nurodanti naudojamą OpenAPI specifikacijos versiją (pvz., "3.0.3" arba "3.1.0"). Tai yra privaloma.
• info: Objektas, teikiantis metaduomenis apie API. Tai apima title (pavadinimą), description (aprašą), jūsų API version (versijos) numerį (ne OAS versijos) ir neprivalomus laukus, tokius kaip contact (kontaktai) ir license (licencija). Ši informacija yra labai svarbi atradimui ir valdymui.

Pavyzdys:

            
openapi: 3.0.3
info:
  title: Global Book Catalog API
  description: An API for accessing a catalog of books from around the world.
  version: 1.0.0
  contact:
    name: API Support Team
    url: http://www.example.com/support
    email: support@example.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

            

              
                Copy
              
            
          

2. `servers` masyvas: kur rasti jūsų API

servers masyvas nurodo pagrindinius jūsų API URL adresus. Galite apibrėžti kelis serverius skirtingoms aplinkoms, tokioms kaip kūrimo, testavimo (staging) ir gamybos (production). Tai leidžia įrankiams lengvai perjungti aplinkas.

Pavyzdys:

            
servers:
  - url: https://api.example.com/v1
    description: Production Server
  - url: https://staging-api.example.com/v1
    description: Staging Server

            

              
                Copy
              
            
          

3. `paths` objektas: API šerdis

Čia apibrėžiami jūsų API galiniai taškai. paths objektas saugo visus individualius URL kelius. Kiekvienas kelio elementas tada aprašo HTTP operacijas (get, post, put, delete ir kt.), kurias galima atlikti su tuo keliu.

Kiekvienoje operacijoje apibrėžiate tokias detales kaip:

• summary ir description: Trumpas ir ilgas paaiškinimas, ką operacija daro.
• operationId: Unikalus identifikatorius, dažnai naudojamas kodo generatorių.
• parameters: Įvesties parametrų masyvas, kurie gali būti kelyje, užklausos eilutėje, antraštėje ar slapuke.
• requestBody: Aprašymas siunčiamo turinio su užklausa (pvz., JSON naujam vartotojui).
• responses: Galimi operacijos rezultatai, apibrėžti HTTP būsenos kodais (pvz., 200 sėkmei, 404 nerasta, 500 serverio klaidai). Kiekvienas atsakymas gali turėti savo aprašą ir turinio schemą.

4. `components` objektas: pernaudojami elementai

Siekdama išvengti pasikartojimo (laikantis DRY principo), OpenAPI suteikia components objektą. Tai galinga funkcija, kurioje galite apibrėžti pernaudojamus elementus ir juos nurodyti visoje specifikacijoje naudodami $ref nuorodas.

• `schemas`: Čia apibrėžiate savo duomenų modelius, naudodami formatą, suderinamą su JSON Schema. Pavyzdžiui, galite vieną kartą apibrėžti User (vartotojo) objektą su savybėmis, tokiomis kaip id, name ir email, ir tada jį nurodyti kiekvienoje užklausoje ar atsakyme, kuris naudoja vartotojo objektą.
• `parameters`: Apibrėžkite bendrus parametrus, tokius kaip userId kelio parametras arba limit užklausos parametras, ir pernaudokite juos skirtingose operacijose.
• `responses`: Apibrėžkite standartinius atsakymus, tokius kaip 404NotFound arba 401Unauthorized, ir taikykite juos, kur reikia.
• `securitySchemes`: Apibrėžkite, kaip klientai autentifikuojasi su jūsų API. OpenAPI palaiko įvairias schemas, įskaitant API raktus, HTTP Basic ir Bearer autentifikaciją bei OAuth 2.0.

5. `security` objektas: autentifikacijos taikymas

Kai apibrėžėte savo securitySchemes komponentuose, security objektas yra naudojamas joms pritaikyti. Galite taikyti saugumą globaliai visai API arba kiekvienai operacijai atskirai, leidžiant derinti viešus ir apsaugotus galinius taškus.

Kodėl jūsų organizacija turėtų priimti OpenAPI: verslo ir techniniai privalumai

OpenAPI specifikacijos priėmimas yra ne tik techninis pasirinkimas; tai strateginis sprendimas, kuris skatina efektyvumą, bendradarbiavimą ir kokybę visame programinės įrangos kūrimo cikle.

Programuotojams: vienintelis tiesos šaltinis

• Aiški komunikacija: OAS suteikia nedviprasmišką kontraktą tarp priekinės (frontend) ir galinės (backend) sistemos komandų, arba tarp paslaugų kūrėjų ir vartotojų. Tai leidžia vykdyti lygiagretų kūrimą, nes abi pusės gali dirbti pagal sutartą specifikaciją, nelaukdamos, kol kita baigs.
• Automatinis kodo generavimas: Su įrankiais, tokiais kaip OpenAPI Generator, programuotojai gali automatiškai generuoti klientų SDK dešimtimis kalbų (Java, Python, JavaScript, Go ir kt.) ir serverių karkasus (stubs). Tai pašalina didžiulį kiekį pasikartojančio kodo ir sumažina rankinių klaidų tikimybę.
• Pagerintas įvedimas į darbą: Nauji programuotojai gali daug greičiau įsivažiuoti, tyrinėdami interaktyvią dokumentaciją, sugeneruotą tiesiogiai iš OpenAPI failo, o ne skaitydami pasenusius wiki puslapius ar išeities kodą.

Produktų vadovams ir architektams: projektavimas ir valdymas

• API-first projektavimas: OpenAPI yra „API-first“ požiūrio kertinis akmuo, kai API kontraktas yra suprojektuojamas ir suderinamas prieš pradedant rašyti bet kokį kodą. Tai užtikrina, kad API nuo pat pradžių atitinka verslo reikalavimus ir vartotojų poreikius.
• Užtikrintas nuoseklumas: Naudodamos pernaudojamus komponentus ir tikrinimo įrankius, tokius kaip „Spectral“, organizacijos gali užtikrinti projektavimo standartus ir nuoseklumą visame savo API landšafte, o tai yra ypač svarbu mikropaslaugų architektūroje.
• Aiškios peržiūros: Specifikacija suteikia aiškų, žmonėms skaitomą formatą architektams ir suinteresuotosioms šalims peržiūrėti ir patvirtinti API dizainus prieš investuojant į kūrimą.

Testuotojams ir kokybės užtikrinimo komandoms: supaprastintas patvirtinimas

• Automatizuotas kontrakto testavimas: OAS failas gali būti naudojamas kaip kontraktas, siekiant automatiškai patikrinti, ar API įgyvendinimas atitinka jo dizainą. Bet koks nukrypimas gali būti pagautas ankstyvoje kūrimo ciklo stadijoje.
• Supaprastintas testų parengimas: Įrankiai, tokie kaip „Postman“ ir „Insomnia“, gali importuoti OpenAPI failą, kad automatiškai sukurtų užklausų kolekciją su galiniais taškais, parametrais ir turinio struktūromis, drastiškai pagreitindami testų paruošimą.
• Imituotų serverių (mock server) generavimas: Įrankiai, tokie kaip „Prism“, gali sugeneruoti dinamišką imituotą serverį iš OpenAPI dokumento, leidžiant priekinės sistemos komandoms ir testuotojams dirbti su realistiška API dar prieš sukuriant galinę sistemą.

Galutiniams vartotojams ir partneriams: geresnė programuotojų patirtis (DX)

• Interaktyvi dokumentacija: Įrankiai, tokie kaip „Swagger UI“ ir „Redoc“, paverčia OpenAPI failą gražia, interaktyvia dokumentacija, kurioje vartotojai gali skaityti apie galinius taškus ir netgi juos išbandyti tiesiogiai naršyklėje.
• Greitesnė integracija: Aiški, tiksli ir mašininiu būdu skaitoma dokumentacija drastiškai sumažina laiką ir pastangas, kurių reikia trečiųjų šalių programuotojams integruotis su jūsų API, taip didinant jos pritaikymą.

Praktinis vadovas: pirmojo OpenAPI dokumento kūrimas

Pritaikykime teoriją praktikoje, sukurdami pagrindinę OpenAPI 3.0 specifikaciją mūsų „Pasauliniam knygų katalogui“. Naudosime YAML dėl jo skaitomumo.

1 žingsnis: apibrėžkite pagrindinę informaciją ir serverius

Pradedame nuo metaduomenų ir gamybos serverio URL.

            
openapi: 3.0.3
info:
  title: Global Book Catalog API
  description: An API for accessing a catalog of books from around the world.
  version: 1.0.0
servers:
  - url: https://api.globalbooks.com/v1

            

              
                Copy
              
            
          

2 žingsnis: apibrėžkite pernaudojamą duomenų modelį `components` dalyje

Prieš apibrėždami galinius taškus, sukurkime pernaudojamą schemą `Book` (knygos) objektui. Tai padės išlaikyti mūsų dizainą švarų ir nuoseklų.

            
components:
  schemas:
    Book:
      type: object
      properties:
        isbn:
          type: string
          description: The International Standard Book Number.
          example: '978-0321765723'
        title:
          type: string
          description: The title of the book.
          example: 'The C++ Programming Language'
        author:
          type: string
          description: The author of the book.
          example: 'Bjarne Stroustrup'
        publicationYear:
          type: integer
          description: The year the book was published.
          example: 2013
      required:
        - isbn
        - title
        - author

            

              
                Copy
              
            
          

3 žingsnis: apibrėžkite galinius taškus `paths` dalyje

Dabar sukursime du galinius taškus: vieną, skirtą gauti knygų sąrašą, ir kitą, skirtą gauti konkrečią knygą pagal jos ISBN.

Atkreipkite dėmesį į $ref: '#/components/schemas/Book' naudojimą. Taip mes nurodome savo pernaudojamą `Book` schemą.

            
paths:
  /books:
    get:
      summary: List all available books
      description: Returns a list of books, optionally filtered.
      operationId: listBooks
      responses:
        '200':
          description: A successful response with an array of books.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'

  /books/{isbn}:
    get:
      summary: Get a book by its ISBN
      description: Returns a single book identified by its ISBN.
      operationId: getBookByIsbn
      parameters:
        - name: isbn
          in: path
          required: true
          description: The ISBN of the book to retrieve.
          schema:
            type: string
      responses:
        '200':
          description: The requested book.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '404':
          description: The book with the specified ISBN was not found.

            

              
                Copy
              
            
          

4 žingsnis: pridėkite saugumą

Apsaugokime savo API paprastu API raktu, kuris turi būti siunčiamas antraštėje. Pirmiausia, apibrėžiame schemą `components` dalyje, tada ją taikome globaliai.

            
# Add this to the 'components' section
components:
  # ... schemas from before
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

# Add this at the root level of the document
security:
  - ApiKeyAuth: []

            

              
                Copy
              
            
          

5 žingsnis: patvirtinkite ir vizualizuokite

Turėdami pilną YAML failą, dabar galite naudoti įvairius įrankius:

• Patvirtinti: Įklijuokite savo kodą į internetinį „Swagger Editor“, kad patikrintumėte sintaksės klaidas ar specifikacijos pažeidimus.
• Vizualizuoti: Naudokite „Swagger UI“ arba „Redoc“, kad sugeneruotumėte gražią, interaktyvią dokumentaciją. Dauguma įrankių reikalauja tik nurodyti jūsų YAML/JSON failą, o jie pasirūpina likusiu darbu.

OpenAPI ekosistema: įrankiai ir technologijos

OAS galią sustiprina jos plati ir brandi įrankių ekosistema. Kad ir koks būtų jūsų poreikis, tikėtina, kad tam yra įrankis:

• Redaktoriai ir tikrintojai (Linters): VS Code su OpenAPI plėtiniais, Stoplight Studio, Swagger Editor ir Spectral (tikrinimui).
• Dokumentacijos generatoriai: Swagger UI (populiariausias), Redoc ir ReadMe.
• Kodo generatoriai: OpenAPI Generator, Swagger Codegen ir įvairūs konkrečioms kalboms skirti įrankiai.
• Testavimas ir imitavimas (Mocking): Postman, Insomnia, Prism ir Mockoon.
• API šliuzai (Gateways) ir valdymas: Dauguma modernių šliuzų, tokių kaip Kong, Tyk, Apigee, ir debesijos paslaugų teikėjų sprendimai (AWS API Gateway, Azure API Management) gali importuoti OpenAPI apibrėžimus, kad sukonfigūruotų maršrutizavimą, saugumą ir užklausų ribojimą.

OpenAPI ateitis: OAS 3.1 ir vėlesnės versijos

OpenAPI specifikacija nuolat tobulėja. Naujausia pagrindinė versija, OAS 3.1, pristatė keletą reikšmingų patobulinimų:

• Visiškas JSON Schema suderinamumas: OAS 3.1 dabar yra 100% suderinama su naujausiu JSON Schema juodraščiu (2020-12). Tai suvienija API specifikacijų ir duomenų modeliavimo pasaulius, leidžiant kurti galingesnes ir standartizuotas schemas.
• Webhook'ai: Ji suteikia standartizuotą būdą aprašyti asinchronines, įvykiais pagrįstas API, kai serveris inicijuoja kontaktą su klientu (pvz., siunčiant pranešimą, kai atnaujinamas užsakymas).
• Užklotai (Overlays) ir standartai: Vykdomas darbas siekiant padaryti specifikacijas модуliаresnes ir pernaudojamas naudojant tokias koncepcijas kaip užklotai, kurie leidžia išplėsti pagrindinę specifikaciją jos nekeičiant.

Šie patobulinimai įtvirtina OpenAPI poziciją kaip centrinį artefaktą modernioje, „API-first“ ir įvykiais pagrįstoje architektūroje.

Išvada: šiuolaikinio programavimo kertinis akmuo

OpenAPI specifikacija pakeitė mūsų požiūrį į API. Ji pakėlė API dokumentaciją nuo baimę keliančios, dažnai apleistos antraeilės užduoties iki strateginio, gyvo dokumento, kuris skatina visą kūrimo ciklą. Veikdama kaip mašininiu būdu skaitomas kontraktas, OAS skatina bendradarbiavimą, įgalina galingą automatizavimą, užtikrina nuoseklumą ir galiausiai veda prie geresnių, patikimesnių ir lengviau naudojamų API kūrimo.

Nesvarbu, ar esate programuotojas, architektas, produkto vadovas ar testuotojas, OpenAPI specifikacijos priėmimas yra esminis žingsnis siekiant įvaldyti šiuolaikinį programinės įrangos kūrimą. Jei dar jos nenaudojate, apsvarstykite galimybę pradėti nuo kito savo projekto. Pirmiausia apibrėžkite kontraktą, pasidalykite juo su savo komanda ir atraskite naują efektyvumo ir aiškumo lygį savo skaitmeniniame bendradarbiavime.